<!DOCTYPE html>
<html lang="en">
  <head>
    <title>SwiftKueryORM  Reference</title>
    <link rel="stylesheet" type="text/css" href="css/jazzy.css" />
    <link rel="stylesheet" type="text/css" href="css/highlight.css" />
    <meta charset="utf-8">
    <script src="js/jquery.min.js" defer></script>
    <script src="js/jazzy.js" defer></script>
    
    <script src="js/lunr.min.js" defer></script>
    <script src="js/typeahead.jquery.js" defer></script>
    <script src="js/jazzy.search.js" defer></script>
  </head>
  <body>


    <a title="SwiftKueryORM  Reference"></a>

    <header class="header">
      <p class="header-col header-col--primary">
        <a class="header-link" href="index.html">
          SwiftKueryORM Docs
        </a>
         (97% documented)
      </p>
    
      <p class="header-col--secondary">
        <form role="search" action="search.json">
          <input type="text" placeholder="Search documentation" data-typeahead>
        </form>
      </p>
    
        <p class="header-col header-col--secondary">
          <a class="header-link" href="https://github.com/IBM-Swift/Swift-Kuery-ORM">
            <img class="header-icon" src="img/gh.png"/>
            View on GitHub
          </a>
        </p>
    
    </header>

    <p class="breadcrumbs">
      <a class="breadcrumb" href="index.html">SwiftKueryORM Reference</a>
      <img class="carat" src="img/carat.png" />
      SwiftKueryORM  Reference
    </p>

    <div class="content-wrapper">
      <nav class="navigation">
        <ul class="nav-groups">
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="Classes.html">Classes</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Classes/Database.html">Database</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Classes/DatabaseDecoder.html">DatabaseDecoder</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Classes/DatabaseEncoder.html">DatabaseEncoder</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Classes.html#/s:13SwiftKueryORM9TableInfoC">TableInfo</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="Extensions.html">Extensions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Extensions/RequestError.html">RequestError</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="Protocols.html">Protocols</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Protocols/Model.html">Model</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="Typealiases.html">Type Aliases</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:13SwiftKueryORM21ConnectionPoolOptionsa">ConnectionPoolOptions</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:13SwiftKueryORM14ExclusiveRangea">ExclusiveRange</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:13SwiftKueryORM11GreaterThana">GreaterThan</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:13SwiftKueryORM18GreaterThanOrEquala">GreaterThanOrEqual</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:13SwiftKueryORM14InclusiveRangea">InclusiveRange</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:13SwiftKueryORM9LowerThana">LowerThan</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:13SwiftKueryORM16LowerThanOrEquala">LowerThanOrEqual</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:13SwiftKueryORM8Orderinga">Ordering</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:13SwiftKueryORM10Paginationa">Pagination</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:13SwiftKueryORM11QueryParamsa">QueryParams</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:13SwiftKueryORM12RequestErrora">RequestError</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="Typealiases.html#/s:13SwiftKueryORM11SQLDataTypea">SQLDataType</a>
              </li>
            </ul>
          </li>
        </ul>
      </nav>
      <article class="main-content">

        <section class="section">
          <div class="section-content">
            
            <p align="center">
    <a href="http://kitura.io/">
        <img src="https://raw.githubusercontent.com/IBM-Swift/Kitura/master/Sources/Kitura/resources/kitura-bird.svg?sanitize=true" height="100" alt="Kitura">
    </a>
</p>

<p align="center">
    <a href="https://ibm-swift.github.io/Swift-Kuery-ORM/index.html">
    <img src="https://img.shields.io/badge/apidoc-SwiftKueryORM-1FBCE4.svg?style=flat" alt="APIDoc">
    </a>
    <a href="https://travis-ci.org/IBM-Swift/Swift-Kuery-ORM">
    <img src="https://travis-ci.org/IBM-Swift/Swift-Kuery-ORM.svg?branch=master" alt="Build Status - Master">
    </a>
    <img src="https://img.shields.io/badge/os-macOS-green.svg?style=flat" alt="macOS">
    <img src="https://img.shields.io/badge/os-linux-green.svg?style=flat" alt="Linux">
    <img src="https://img.shields.io/badge/license-Apache2-blue.svg?style=flat" alt="Apache 2">
    <a href="http://swift-at-ibm-slack.mybluemix.net/">
    <img src="http://swift-at-ibm-slack.mybluemix.net/badge.svg" alt="Slack Status">
    </a>
</p>
<h1 id='swift-kuery-orm' class='heading'>Swift-Kuery-ORM</h1>

<p>Swift-Kuery-ORM is an ORM (Object Relational Mapping) library built for Swift. Using it allows you to simplify persistence of model objects with your server.</p>

<p>Swift-Kuery-ORM is built on top of <a href="http://github.com/IBM-Swift/Swift-Kuery">Swift-Kuery</a>, which means that its possible to use Swift-Kuery to customize SQL queries made to the database, if the functionality of the ORM is insufficient.</p>
<h2 id='the-model-protocol' class='heading'>The Model Protocol</h2>

<p>The key component of Swift-Kuery-ORM is the protocol <code><a href="Protocols/Model.html">Model</a></code>.</p>

<p>Let&rsquo;s propose a struct to use as an example. We can declare an object that looks like so:</p>
<pre class="highlight swift"><code><span class="kd">struct</span> <span class="kt">Grade</span><span class="p">:</span> <span class="kt">Codable</span> <span class="p">{</span>
  <span class="k">var</span> <span class="nv">course</span><span class="p">:</span> <span class="kt">String</span>
  <span class="k">var</span> <span class="nv">grade</span><span class="p">:</span> <span class="kt">Int</span>
<span class="p">}</span>
</code></pre>

<p>Thanks to <a href="https://developer.ibm.com/swift/2017/10/30/codable-routing/">Codable Routing</a> in Kitura 2.0, we declare our struct to be <code>Codable</code> to simplify our RESTful routes for these objects on our server. The <code><a href="Protocols/Model.html">Model</a></code> protocol extends what <code>Codable</code> does to work with the ORM. In your server application, you would extend your object like so:</p>
<pre class="highlight swift"><code><span class="kd">extension</span> <span class="kt">Grade</span><span class="p">:</span> <span class="kt">Model</span> <span class="p">{</span> <span class="p">}</span>
</code></pre>

<p>Now that your <code>Grade</code> struct conforms to <code><a href="Protocols/Model.html">Model</a></code>, after you have set up your database connection pool and created a database table, you automatically have access to a slew of convenience functions for your object.</p>

<p>Need to retrieve all instances of <code>Grade</code>? You can implement:</p>
<pre class="highlight swift"><code><span class="kt">Grade</span><span class="o">.</span><span class="nf">findAll</span><span class="p">()</span>
</code></pre>

<p>Need to add a new instance of <code>Grade</code>? Here&rsquo;s how:</p>
<pre class="highlight swift"><code><span class="n">grade</span><span class="o">.</span><span class="nf">save</span><span class="p">()</span>
</code></pre>

<p>The <code><a href="Protocols/Model.html">Model</a></code> protocol is the key to using the ORM. Let&rsquo;s walk through how to fully set up an application to make use of the ORM.</p>
<h2 id='example' class='heading'>Example</h2>

<p>Follow <a href="https://www.kitura.io/guides/gettingstarted.html">Getting Started</a> to create a Kitura server. In this example you&rsquo;ll be using the <a href="https://github.com/IBM-Swift/Swift-Kuery-PostgreSQL">Swift Kuery PostgreSQL plugin</a>, so you will need PostgreSQL running on your local machine, which you can install with <code>brew install postgresql</code>. The default port for PostgreSQL is 5432.</p>
<h3 id='update-your-package-swift-file' class='heading'>Update your Package.swift file</h3>

<p>Add Swift-Kuery-ORM and Swift-Kuery-PostgreSQL to your application&rsquo;s <code>Package.swift</code>. Substitute <code>&quot;x.x.x&quot;</code> with the latest <code>Swift-Kuery-ORM</code> <a href="https://github.com/IBM-Swift/Swift-Kuery-ORM/releases">release</a> and the latest <code>Swift-Kuery-PostgreSQL</code> <a href="https://github.com/IBM-Swift/Swift-Kuery-PostgreSQL/releases">release</a>.</p>
<pre class="highlight swift"><code><span class="nv">dependencies</span><span class="p">:</span> <span class="p">[</span>
    <span class="o">...</span>
    <span class="c1">// Add these two lines</span>
    <span class="o">.</span><span class="nf">package</span><span class="p">(</span><span class="nv">url</span><span class="p">:</span> <span class="s">"https://github.com/IBM-Swift/Swift-Kuery-ORM.git"</span><span class="p">,</span> <span class="nv">from</span><span class="p">:</span> <span class="s">"x.x.x"</span><span class="p">),</span>
    <span class="o">.</span><span class="nf">package</span><span class="p">(</span><span class="nv">url</span><span class="p">:</span> <span class="s">"https://github.com/IBM-Swift/Swift-Kuery-PostgreSQL.git"</span><span class="p">,</span> <span class="nv">from</span><span class="p">:</span> <span class="s">"x.x.x"</span><span class="p">),</span>
  <span class="p">],</span>
  <span class="nv">targets</span><span class="p">:</span> <span class="p">[</span>
    <span class="o">.</span><span class="nf">target</span><span class="p">(</span>
      <span class="nv">name</span><span class="p">:</span> <span class="o">...</span>
      <span class="c1">// Add these two modules to your target(s)</span>
      <span class="nv">dependencies</span><span class="p">:</span> <span class="p">[</span><span class="o">...</span><span class="p">,</span> <span class="s">"SwiftKueryORM"</span><span class="p">,</span> <span class="s">"SwiftKueryPostgreSQL"</span><span class="p">]),</span>
  <span class="p">]</span>
</code></pre>

<p>Let&rsquo;s assume you want to add ORM functionality to a file called <code>Application.swift</code>. You&rsquo;ll need to add the following import statements at the top of the file:</p>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">SwiftKueryORM</span>
<span class="kd">import</span> <span class="kt">SwiftKueryPostgreSQL</span>
</code></pre>
<h3 id='create-your-database' class='heading'>Create Your Database</h3>

<p>As mentioned before, we recommend you use <a href="https://brew.sh">Homebrew</a> to set up PostgreSQL on your machine. You can install PostgreSQL and set up your table like so:</p>
<pre class="highlight shell"><code>brew <span class="nb">install </span>postgresql
brew services start postgresql
createdb school
</code></pre>

<p>Initialize your database in your <code>Application.swift</code> file:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">pool</span> <span class="o">=</span> <span class="kt">PostgreSQLConnection</span><span class="o">.</span><span class="nf">createPool</span><span class="p">(</span><span class="nv">host</span><span class="p">:</span> <span class="s">"localhost"</span><span class="p">,</span> <span class="nv">port</span><span class="p">:</span> <span class="mi">5432</span><span class="p">,</span> <span class="nv">options</span><span class="p">:</span> <span class="p">[</span><span class="o">.</span><span class="nf">databaseName</span><span class="p">(</span><span class="s">"school"</span><span class="p">)],</span> <span class="nv">poolOptions</span><span class="p">:</span> <span class="kt">ConnectionPoolOptions</span><span class="p">(</span><span class="nv">initialCapacity</span><span class="p">:</span> <span class="mi">10</span><span class="p">,</span> <span class="nv">maxCapacity</span><span class="p">:</span> <span class="mi">50</span><span class="p">,</span> <span class="nv">timeout</span><span class="p">:</span> <span class="mi">10000</span><span class="p">))</span>
<span class="kt">Database</span><span class="o">.</span><span class="k">default</span> <span class="o">=</span> <span class="kt">Database</span><span class="p">(</span><span class="n">pool</span><span class="p">)</span>
</code></pre>
<h3 id='set-up-your-object' class='heading'>Set Up Your Object</h3>

<p>Like before, assume you will work with a struct that looks like so:</p>
<pre class="highlight swift"><code><span class="kd">struct</span> <span class="kt">Grade</span> <span class="p">:</span> <span class="kt">Codable</span> <span class="p">{</span>
  <span class="k">var</span> <span class="nv">course</span><span class="p">:</span> <span class="kt">String</span>
  <span class="k">var</span> <span class="nv">grade</span><span class="p">:</span> <span class="kt">Int</span>
<span class="p">}</span>
</code></pre>

<p>In your <code>Application.swift</code> file, extend <code>Grade</code> to conform to <code><a href="Protocols/Model.html">Model</a></code></p>
<pre class="highlight swift"><code><span class="kd">extension</span> <span class="kt">Grade</span> <span class="p">:</span> <span class="kt">Model</span> <span class="p">{</span>
    <span class="c1">// here, you can add any server-side specific logic to your object</span>
<span class="p">}</span>
</code></pre>

<p>Now, you need to create your table. If you are configuring your database while you start up your server, you can use <code>createTableSync()</code>, which runs synchronously. If you want to use an asynchronous function, you can use <code>createTable()</code> elsewhere. You can implement either of these functions like so:</p>
<pre class="highlight swift"><code><span class="k">do</span> <span class="p">{</span>
  <span class="k">try</span> <span class="kt">Grade</span><span class="o">.</span><span class="nf">createTableSync</span><span class="p">()</span>
<span class="p">}</span> <span class="k">catch</span> <span class="k">let</span> <span class="nv">error</span> <span class="p">{</span>
  <span class="c1">// Error</span>
<span class="p">}</span>
</code></pre>

<p>It&rsquo;s important to point out that if you&rsquo;ve already created your table, this will throw an error here.</p>

<p>Your application is now ready to make use of all the functions available in the <code><a href="Protocols/Model.html">Model</a></code> protocol. If you&rsquo;d like to see a fully working example of the ORM using <a href="https://www.ibm.com/blogs/bluemix/2018/01/kitura-2-0-taking-advantage-of-codable-routes/">Codable Routing</a>, visit our <a href="https://github.com/IBM/foodtrackerbackend">FoodTracker</a> example.</p>

<p>Let&rsquo;s cover all the functionality you have available to you now.</p>
<h3 id='saving' class='heading'>Saving</h3>

<p>If you&rsquo;d like to save a new object to your database, you have to create the object and use the <code>save()</code> function:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">grade</span> <span class="o">=</span> <span class="kt">Grade</span><span class="p">(</span><span class="nv">course</span><span class="p">:</span> <span class="s">"physics"</span><span class="p">,</span> <span class="nv">grade</span><span class="p">:</span> <span class="mi">80</span><span class="p">)</span>
<span class="n">grade</span><span class="o">.</span><span class="n">save</span> <span class="p">{</span> <span class="n">grade</span><span class="p">,</span> <span class="n">error</span> <span class="k">in</span>
  <span class="o">...</span>
<span class="p">}</span>
</code></pre>

<p>You also optionally have the ability to pass the ID of the newly saved object into your closure. Add it to the collection of parameters like so:</p>
<pre class="highlight swift"><code><span class="n">grade</span><span class="o">.</span><span class="n">save</span> <span class="p">{</span> <span class="p">(</span><span class="nv">id</span><span class="p">:</span> <span class="kt">Int</span><span class="p">?,</span> <span class="nv">grade</span><span class="p">:</span> <span class="kt">Grade</span><span class="p">?,</span> <span class="nv">error</span><span class="p">:</span> <span class="kt">RequestError</span><span class="p">?)</span> <span class="k">in</span>
  <span class="o">...</span>
<span class="p">}</span>
</code></pre>
<h3 id='updating' class='heading'>Updating</h3>

<p>If you have the id for an existing record of your object, and you&rsquo;d like to update the record with an object, you can use the <code>update()</code> function to do so:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">grade</span> <span class="o">=</span> <span class="kt">Grade</span><span class="p">(</span><span class="nv">course</span><span class="p">:</span> <span class="s">"physics"</span><span class="p">,</span> <span class="nv">grade</span><span class="p">:</span> <span class="mi">80</span><span class="p">)</span>
<span class="n">grade</span><span class="o">.</span><span class="n">course</span> <span class="o">=</span> <span class="s">"maths"</span>

<span class="n">grade</span><span class="o">.</span><span class="nf">update</span><span class="p">(</span><span class="nv">id</span><span class="p">:</span> <span class="mi">1</span><span class="p">)</span> <span class="p">{</span> <span class="n">grade</span><span class="p">,</span> <span class="n">error</span> <span class="k">in</span>
  <span class="o">...</span>
<span class="p">}</span>
</code></pre>
<h3 id='retrieving' class='heading'>Retrieving</h3>

<p>If you&rsquo;d like to find a specific object, and you have its id, you can use the <code>find()</code> function to retrieve it:</p>
<pre class="highlight swift"><code><span class="kt">Grade</span><span class="o">.</span><span class="nf">find</span><span class="p">(</span><span class="nv">id</span><span class="p">:</span> <span class="mi">1</span><span class="p">)</span> <span class="p">{</span> <span class="n">result</span><span class="p">,</span> <span class="n">error</span> <span class="k">in</span>
  <span class="o">...</span>
<span class="p">}</span>
</code></pre>

<p>If you&rsquo;d like to retrieve all instances of a particular object, you can make use of <code>findAll()</code> as a static function on the type you are trying to retrieve:</p>
<pre class="highlight swift"><code><span class="kt">Grade</span><span class="o">.</span><span class="n">findAll</span> <span class="p">{</span> <span class="p">(</span><span class="nv">result</span><span class="p">:</span> <span class="p">[</span><span class="kt">Grade</span><span class="p">]?,</span> <span class="nv">error</span><span class="p">:</span> <span class="kt">RequestError</span><span class="p">?)</span> <span class="k">in</span>
  <span class="o">...</span>
<span class="p">}</span>
</code></pre>

<p>You also have the ability to form your results in different ways and formats, like so:</p>
<pre class="highlight swift"><code><span class="kt">Grade</span><span class="o">.</span><span class="n">findAll</span> <span class="p">{</span> <span class="p">(</span><span class="nv">result</span><span class="p">:</span> <span class="p">[(</span><span class="kt">Int</span><span class="p">,</span> <span class="kt">Grade</span><span class="p">)]?,</span> <span class="nv">error</span><span class="p">:</span> <span class="kt">RequestError</span><span class="p">?)</span> <span class="k">in</span>
  <span class="o">...</span>
<span class="p">}</span>

<span class="kt">Grade</span><span class="o">.</span><span class="n">findAll</span> <span class="p">{</span> <span class="p">(</span><span class="nv">result</span><span class="p">:</span> <span class="p">[</span><span class="kt">Int</span><span class="p">:</span> <span class="kt">Grade</span><span class="p">]?,</span> <span class="nv">error</span><span class="p">:</span> <span class="kt">RequestError</span><span class="p">?)</span> <span class="k">in</span>
  <span class="o">...</span>
<span class="p">}</span>
</code></pre>
<h3 id='deleting' class='heading'>Deleting</h3>

<p>If you&rsquo;d like to delete an object, and you have its id, you can use the <code>delete()</code> function like so:</p>
<pre class="highlight swift"><code><span class="kt">Grade</span><span class="o">.</span><span class="nf">delete</span><span class="p">(</span><span class="nv">id</span><span class="p">:</span> <span class="mi">1</span><span class="p">)</span> <span class="p">{</span> <span class="n">error</span> <span class="k">in</span>
  <span class="o">...</span>
<span class="p">}</span>
</code></pre>

<p>If you&rsquo;re feeling bold, and you&rsquo;d like to remove all instances of an object from your database, you can use the static function <code>deleteAll()</code> with your type:</p>
<pre class="highlight swift"><code><span class="kt">Grade</span><span class="o">.</span><span class="n">deleteAll</span> <span class="p">{</span> <span class="n">error</span> <span class="k">in</span>
  <span class="o">...</span>
<span class="p">}</span>
</code></pre>
<h3 id='customizing-your-model' class='heading'>Customizing your Model</h3>

<p>The ORM defines an extension to <code><a href="Protocols/Model.html">Model</a></code> which provides a number of <code>public static executeQuery(…)</code> functions. These can be used to create custom functions within your model that perform more complex database operations. The example below defines a Person model and with a custom function that will retrieve all records which have age &gt; 20:</p>
<pre class="highlight swift"><code><span class="c1">// define the Person struct</span>
<span class="kd">struct</span> <span class="kt">Person</span><span class="p">:</span> <span class="kt">Codable</span> <span class="p">{</span>
    <span class="k">var</span> <span class="nv">firstname</span><span class="p">:</span> <span class="kt">String</span>
    <span class="k">var</span> <span class="nv">surname</span><span class="p">:</span> <span class="kt">String</span>
    <span class="k">var</span> <span class="nv">age</span><span class="p">:</span> <span class="kt">Int</span>
<span class="p">}</span>

<span class="c1">// extend Person to conform to model and add overTwenties function</span>
<span class="kd">extension</span> <span class="kt">Person</span><span class="p">:</span> <span class="kt">Model</span> <span class="p">{</span>

    <span class="c1">// Define a synchronous function to retrieve all records of Person with age &gt; 20</span>
    <span class="kd">public</span> <span class="kd">static</span> <span class="kd">func</span> <span class="nf">getOverTwenties</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="p">[</span><span class="kt">Person</span><span class="p">]?</span> <span class="p">{</span>
        <span class="k">let</span> <span class="nv">wait</span> <span class="o">=</span> <span class="kt">DispatchSemaphore</span><span class="p">(</span><span class="nv">value</span><span class="p">:</span> <span class="mi">0</span><span class="p">)</span>
        <span class="c1">// First get the table</span>
        <span class="k">var</span> <span class="nv">table</span><span class="p">:</span> <span class="kt">Table</span>
        <span class="k">do</span> <span class="p">{</span>
            <span class="n">table</span> <span class="o">=</span> <span class="k">try</span> <span class="kt">Person</span><span class="o">.</span><span class="nf">getTable</span><span class="p">()</span>
        <span class="p">}</span> <span class="k">catch</span> <span class="p">{</span>
            <span class="c1">// Handle error</span>
        <span class="p">}</span>
        <span class="c1">// Define result, query and execute</span>
        <span class="k">var</span> <span class="nv">overTwenties</span><span class="p">:</span> <span class="p">[</span><span class="kt">Person</span><span class="p">]?</span> <span class="o">=</span> <span class="kc">nil</span>
        <span class="k">let</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">Select</span><span class="p">(</span><span class="nv">from</span><span class="p">:</span> <span class="n">table</span><span class="p">)</span><span class="o">.</span><span class="nf">where</span><span class="p">(</span><span class="s">"age &gt; 20"</span><span class="p">)</span>

        <span class="kt">Person</span><span class="o">.</span><span class="nf">executeQuery</span><span class="p">(</span><span class="nv">query</span><span class="p">:</span> <span class="n">query</span><span class="p">,</span> <span class="nv">parameters</span><span class="p">:</span> <span class="kc">nil</span><span class="p">)</span> <span class="p">{</span> <span class="n">results</span><span class="p">,</span> <span class="n">error</span> <span class="k">in</span>
            <span class="k">guard</span> <span class="k">let</span> <span class="nv">results</span> <span class="o">=</span> <span class="n">results</span> <span class="k">else</span> <span class="p">{</span>
                <span class="c1">// Handle error</span>
            <span class="p">}</span>
            <span class="n">overTwenties</span> <span class="o">=</span> <span class="n">results</span>
            <span class="n">wait</span><span class="o">.</span><span class="nf">signal</span><span class="p">()</span>
            <span class="k">return</span>
        <span class="p">}</span>
        <span class="n">wait</span><span class="o">.</span><span class="nf">wait</span><span class="p">()</span>
        <span class="k">return</span> <span class="n">overTwenties</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre>

<p>Alternatively you can define and asynchronous getOverTwenties function:</p>
<pre class="highlight swift"><code><span class="kd">public</span> <span class="kd">static</span> <span class="kd">func</span> <span class="nf">getOverTwenties</span><span class="p">(</span><span class="nv">oncompletion</span><span class="p">:</span> <span class="kd">@escaping</span> <span class="p">([</span><span class="kt">Person</span><span class="p">]?,</span> <span class="kt">RequestError</span><span class="p">?)</span><span class="o">-&gt;</span> <span class="kt">Void</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">var</span> <span class="nv">table</span><span class="p">:</span> <span class="kt">Table</span>
    <span class="k">do</span> <span class="p">{</span>
        <span class="n">table</span> <span class="o">=</span> <span class="k">try</span> <span class="kt">Person</span><span class="o">.</span><span class="nf">getTable</span><span class="p">()</span>
    <span class="p">}</span> <span class="k">catch</span> <span class="p">{</span>
        <span class="c1">// Handle error</span>
    <span class="p">}</span>
    <span class="k">let</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">Select</span><span class="p">(</span><span class="nv">from</span><span class="p">:</span> <span class="n">table</span><span class="p">)</span><span class="o">.</span><span class="nf">where</span><span class="p">(</span><span class="s">"age &gt; 20"</span><span class="p">)</span>
    <span class="kt">Person</span><span class="o">.</span><span class="nf">executeQuery</span><span class="p">(</span><span class="nv">query</span><span class="p">:</span> <span class="n">query</span><span class="p">,</span> <span class="nv">parameters</span><span class="p">:</span> <span class="kc">nil</span><span class="p">,</span> <span class="n">oncompletion</span><span class="p">)</span>
<span class="p">}</span>
</code></pre>

<p>which can be called in a fashion similar to the following:</p>
<pre class="highlight swift"><code><span class="kt">Person</span><span class="o">.</span><span class="nf">getOverTwenties</span><span class="p">()</span> <span class="p">{</span> <span class="n">result</span><span class="p">,</span> <span class="n">error</span> <span class="k">in</span>
    <span class="k">guard</span> <span class="k">let</span> <span class="nv">result</span> <span class="o">=</span> <span class="n">result</span> <span class="k">else</span> <span class="p">{</span>
        <span class="c1">// Handle error</span>
    <span class="p">}</span>
    <span class="c1">// Use result</span>
<span class="p">}</span>
</code></pre>

<p>If you&rsquo;d like to learn more about how you can customize queries, check out the <a href="https://github.com/IBM-Swift/Swift-Kuery">Swift-Kuery</a> repository for more information.</p>
<h2 id='model-identifiers' class='heading'>Model Identifiers</h2>

<p>The ORM has several options available for identifying an instance of a model.</p>
<h3 id='automatic-id-assignment' class='heading'>Automatic ID assignment</h3>

<p>If you define your <code><a href="Protocols/Model.html">Model</a></code> without specifying an ID property, either by using the <code>idColumnName</code> property or the default name of <code>id</code>, then the ORM will create an auto-incrementing column named <code>id</code> in the database table for the model, eg.</p>
<pre class="highlight swift"><code><span class="kd">struct</span> <span class="kt">Person</span><span class="p">:</span> <span class="kt">Model</span> <span class="p">{</span>
    <span class="k">var</span> <span class="nv">firstname</span><span class="p">:</span> <span class="kt">String</span>
    <span class="k">var</span> <span class="nv">surname</span><span class="p">:</span> <span class="kt">String</span>
    <span class="k">var</span> <span class="nv">age</span><span class="p">:</span> <span class="kt">Int</span>
<span class="p">}</span>
</code></pre>

<p>The model does not contain a property for the ID. The ORM provides a specific <code>save</code> API that will return the ID that was assigned. It is important to note the ORM will not link the returned ID to the instance of the Model in any way; you are responsible for maintaining this relationship if necessary. Below is an example of retrieving an ID for an instance of the <code>Person</code> model defined above:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">person</span> <span class="o">=</span> <span class="kt">Person</span><span class="p">(</span><span class="nv">firstname</span><span class="p">:</span> <span class="s">"example"</span><span class="p">,</span> <span class="nv">surname</span><span class="p">:</span> <span class="s">"person"</span><span class="p">,</span> <span class="nv">age</span><span class="p">:</span> <span class="mi">21</span><span class="p">)</span>
<span class="n">person</span><span class="o">.</span><span class="nf">save</span><span class="p">()</span> <span class="p">{</span> <span class="p">(</span><span class="nv">id</span><span class="p">:</span> <span class="kt">Int</span><span class="p">?,</span> <span class="n">person</span><span class="p">,</span> <span class="n">error</span><span class="p">)</span> <span class="k">in</span>
    <span class="k">guard</span> <span class="k">let</span> <span class="nv">id</span> <span class="o">=</span> <span class="n">id</span><span class="p">,</span> <span class="k">let</span> <span class="nv">person</span> <span class="o">=</span> <span class="n">person</span> <span class="k">else</span><span class="p">{</span>
        <span class="c1">// Handle error</span>
        <span class="k">return</span>
    <span class="p">}</span>
    <span class="c1">// Use person and id</span>
<span class="p">}</span>
</code></pre>

<p>The compiler requires you to declare the type of the ID received by your completion handler; the type should be <code>Int?</code> for an ID that has been automatically assigned.</p>
<h3 id='manual-id-assignment' class='heading'>Manual ID assignment</h3>

<p>You can manage the assignment of IDs yourself by adding an <code>id</code> property to your model. You may customise the name of this property by defining <code>idColumnName</code>. For example:</p>
<pre class="highlight swift"><code><span class="kd">struct</span> <span class="kt">Person</span><span class="p">:</span> <span class="kt">Model</span> <span class="p">{</span>
    <span class="k">var</span> <span class="nv">myIDField</span><span class="p">:</span> <span class="kt">Int</span>
    <span class="k">var</span> <span class="nv">firstname</span><span class="p">:</span> <span class="kt">String</span>
    <span class="k">var</span> <span class="nv">surname</span><span class="p">:</span> <span class="kt">String</span>
    <span class="k">var</span> <span class="nv">age</span><span class="p">:</span> <span class="kt">Int</span>

    <span class="kd">static</span> <span class="k">var</span> <span class="nv">idColumnName</span> <span class="o">=</span> <span class="s">"myIDField"</span>
    <span class="kd">static</span> <span class="k">var</span> <span class="nv">idColumnType</span> <span class="o">=</span> <span class="kt">Int</span><span class="o">.</span><span class="k">self</span>
<span class="p">}</span>
</code></pre>

<p>When using a <code><a href="Protocols/Model.html">Model</a></code> defined in this way, you are responsible for the assignment and management of IDs. Below is an example of saving an instance of the <code>Person</code> model defined above:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">person</span> <span class="o">=</span> <span class="kt">Person</span><span class="p">(</span><span class="nv">myIDField</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="nv">firstname</span><span class="p">:</span> <span class="s">"example"</span><span class="p">,</span> <span class="nv">surname</span><span class="p">:</span> <span class="s">"person"</span><span class="p">,</span> <span class="nv">age</span><span class="p">:</span> <span class="mi">21</span><span class="p">)</span>
<span class="n">person</span><span class="o">.</span><span class="nf">save</span><span class="p">()</span> <span class="p">{</span> <span class="p">(</span><span class="n">person</span><span class="p">,</span> <span class="n">error</span><span class="p">)</span> <span class="k">in</span>
    <span class="k">guard</span> <span class="k">let</span> <span class="nv">person</span> <span class="o">=</span> <span class="n">person</span> <span class="k">else</span> <span class="p">{</span>
        <span class="c1">// Handle error</span>
        <span class="k">return</span>
    <span class="p">}</span>
    <span class="c1">// Use newly saved person</span>
<span class="p">}</span>
</code></pre>
<h3 id='using-code-optional-code-id-properties' class='heading'>Using <code>optional</code> ID properties</h3>

<p>Declaring your ID property as optional allows the ORM to assign the ID automatically when the model is saved. If the value of ID is <code>nil</code>, the database will assign an auto-incremented value. At present this is only support for an <code>Int?</code> type.</p>

<p>You may instead provide an explicit value, which will be used instead of automatic assignment.</p>

<p>Optional IDs must be identified by defining the <code>idKeypath: IDKeyPath</code> property, as in the example below:</p>
<pre class="highlight swift"><code><span class="kd">struct</span> <span class="kt">Person</span><span class="p">:</span> <span class="kt">Model</span> <span class="p">{</span>
    <span class="k">var</span> <span class="nv">id</span><span class="p">:</span> <span class="kt">Int</span><span class="p">?</span>
    <span class="k">var</span> <span class="nv">firstname</span><span class="p">:</span> <span class="kt">String</span>
    <span class="k">var</span> <span class="nv">surname</span><span class="p">:</span> <span class="kt">String</span>
    <span class="k">var</span> <span class="nv">age</span><span class="p">:</span> <span class="kt">Int</span>

    <span class="kd">static</span> <span class="k">var</span> <span class="nv">idKeypath</span><span class="p">:</span> <span class="kt">IDKeyPath</span> <span class="o">=</span> <span class="p">\</span><span class="kt">Person</span><span class="o">.</span><span class="n">id</span>
<span class="p">}</span>
</code></pre>

<p>In the example above, the <code><a href="Protocols/Model.html">Model</a></code> is defined with an ID property matching the default <code>idColumnName</code> value, but should you wish to use an alternative name you must define <code>idColumnName</code> accordingly.</p>

<p>Below is an example of saving an instance of the <code>Person</code> defined above, both with an explicitly defined ID and without:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">person</span> <span class="o">=</span> <span class="kt">Person</span><span class="p">(</span><span class="nv">id</span><span class="p">:</span> <span class="kc">nil</span><span class="p">,</span> <span class="nv">firstname</span><span class="p">:</span> <span class="err">“</span><span class="kt">Banana</span><span class="err">”</span><span class="p">,</span> <span class="nv">surname</span><span class="p">:</span> <span class="err">“</span><span class="kt">Man</span><span class="err">”</span><span class="p">,</span> <span class="nv">age</span><span class="p">:</span> <span class="mi">21</span><span class="p">)</span>
<span class="k">let</span> <span class="nv">specificPerson</span> <span class="o">=</span> <span class="kt">Person</span><span class="p">(</span><span class="nv">id</span><span class="p">:</span> <span class="mi">5</span><span class="p">,</span> <span class="nv">firstname</span><span class="p">:</span> <span class="err">“</span><span class="kt">Super</span><span class="err">”</span><span class="p">,</span> <span class="nv">surname</span><span class="p">:</span> <span class="err">“</span><span class="kt">Ted</span><span class="err">”</span><span class="p">,</span> <span class="nv">age</span><span class="p">:</span> <span class="mi">26</span><span class="p">)</span>

<span class="n">person</span><span class="o">.</span><span class="nf">save</span><span class="p">()</span> <span class="p">{</span> <span class="p">(</span><span class="n">savedPerson</span><span class="p">,</span> <span class="n">error</span><span class="p">)</span> <span class="k">in</span>
        <span class="k">guard</span> <span class="k">let</span> <span class="nv">newPerson</span> <span class="o">=</span> <span class="n">savedPerson</span> <span class="k">else</span> <span class="p">{</span>
            <span class="c1">// Handle error</span>
        <span class="p">}</span>
        <span class="nf">print</span><span class="p">(</span><span class="n">newPerson</span><span class="o">.</span><span class="n">id</span><span class="p">)</span> <span class="c1">// Prints the next value in the databases identifier sequence, eg. 1</span>
<span class="p">}</span>

<span class="n">specificPerson</span><span class="o">.</span><span class="nf">save</span><span class="p">()</span> <span class="p">{</span> <span class="p">(</span><span class="n">savedPerson</span><span class="p">,</span> <span class="n">error</span><span class="p">)</span> <span class="k">in</span>
        <span class="k">guard</span> <span class="k">let</span> <span class="nv">newPerson</span> <span class="o">=</span> <span class="n">savedPerson</span> <span class="k">else</span> <span class="p">{</span>
            <span class="c1">// Handle error</span>
        <span class="p">}</span>
        <span class="nf">print</span><span class="p">(</span><span class="n">newPerson</span><span class="o">.</span><span class="n">id</span><span class="p">)</span> <span class="c1">// Prints 5</span>
<span class="p">}</span>
</code></pre>

<p><strong>NOTE</strong> - When using manual or optional ID properties, you should be prepared to handle violation of unique identifier constraints. These can occur if you attempt to save a model with an ID that already exists, or in the case of Postgres, if the auto-incremented value collides with an ID that was previously inserted explicitly.</p>
<h2 id='list-of-plugins' class='heading'>List of plugins</h2>

<ul>
<li><p><a href="https://github.com/IBM-Swift/Swift-Kuery-PostgreSQL">PostgreSQL</a></p></li>
<li><p><a href="https://github.com/IBM-Swift/Swift-Kuery-SQLite">SQLite</a></p></li>
<li><p><a href="https://github.com/IBM-Swift/SwiftKueryMySQL">MySQL</a></p></li>
</ul>
<h2 id='api-documentation' class='heading'>API Documentation</h2>

<p>For more information visit our <a href="https://ibm-swift.github.io/Swift-Kuery-ORM/index.html">API reference</a>.</p>
<h2 id='community' class='heading'>Community</h2>

<p>We love to talk server-side Swift, and Kitura. Join our <a href="http://swift-at-ibm-slack.mybluemix.net/">Slack</a> to meet the team!</p>
<h2 id='license' class='heading'>License</h2>

<p>This library is licensed under Apache 2.0. Full license text is available in <a href="LICENSE.txt">LICENSE</a>.</p>

          </div>
        </section>


      </article>
    </div>
    <section class="footer">
      <p>&copy; 2019 <a class="link" href="" target="_blank" rel="external">IBM</a>. All rights reserved. (Last updated: 2019-04-01)</p>
      <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.9.1</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
    </section>
  </body>
</div>
</html>
